/******************************************************************************
**                                                                           **
**                 Proprietary and Confidential Information                  **
**                                                                           **
**                 Copyright (c) Conexant, Inc. Unpublished                  **
**                                                                           **
** This source code and the algorithms implemented therein constitute        **
** confidential information and may compromise trade secrets of Conexant Systems,    **
** Inc. or its associates, and any unauthorized use thereof is prohibited.   **
**                                                                           **
******************************************************************************/
#ifndef __DC_PRINTER_CONTROL_API_H__
#define __DC_PRINTER_CONTROL_API_H__

#ifdef __cplusplus
extern "C" {
#endif

#define	PR_VERSION	21		/* 2_1 */

#include "dc_type.h"
#include "dc_return_codes.h"
#include "dc_log_api.h"
#include "dc_imgbuf_api.h"

/**************************************************************************
*  file: dc_printer_control_api.h
*  @brief This file contains the definition of the common Conexant Printer 
*  API.
* 
*  Print subsystems vary significantly from AIO to AIO.  Variations include 
*  marking technology (inkjet, laser, dye-sub), performance characteristics, 
*  supported media types and sizes, printing options (2-up, duplex), and
*  many more.  To insulate the bulk of the system firmware from printer 
*  subsystem variations, it is convenient to develop a print subsystem 
*  abstraction which offers clients of the print subsystem a common 
*  interface and printer model, independent of the underlying printer 
*  technology. 
******************************************************************************/
/******************************************************************************
*  FILE FORMAT: <PUBLIC>
*      1. INCLUDES 
*      2. ENUMERATIONS 
*      3. DEFINES
*      4. STRUCTURES
*      5. GLOBALS
*      6. PUBLIC FUNCTION PROTOTYPES
******************************************************************************/

/******************************************************************************
*  1. INCLUDES
******************************************************************************/

#include "dc_printer_media_api.h" // Printer media definitions
#if 1
typedef UINT32 PR_QUALITY;
typedef UINT32 PR_UTILITY_TYPE;
#else
# include "dc_printer_custom_api.h" // Printer-specific portion of the Printer API
#endif

/******************************************************************************
*  2. ENUMERATIONS
******************************************************************************/

typedef enum
{
    /**
    ** This status type is for job status such as page ejection, job 
    ** completion, etc. User intervention is not typically required for
    ** these events.
    */
    PR_STATUS_TYPE_INFORMATIONAL,

    /**
    ** This status type is reserved for warnings including low ink, low
    ** toner, etc. User intervention may be required for these events.
    */
    PR_STATUS_TYPE_WARNING,

    /**
    ** This status type is reserved for errors including paper jam, 
    ** motor stall, etc. User intervention is nearly always required 
    ** for these events.
    */
    PR_STATUS_TYPE_ERROR,

    /** add this item for the code convinenit and reduce compiler error
     **  for the initiliazation of related struction/vars
    */
    PR_STATUS_TYPE_LAST,
} PR_STATUS_TYPE;

# define PR_STATUS_TYPE_STRING "INFO", \
                               "WARNING", \
                               "ERROR"

typedef UINT32 PR_STATUS_EVENT;

typedef enum
{
    // Send the print to the power ON and idle state. The definition of 
    // this request depends on the printer. 
    PR_POWER_ON,

    // Send the print to the power OFF state. The definition of this 
    // request depends on the printer.
    PR_POWER_OFF,

    // When the printer is idle, this request causes the printer to 
    // perform any work to enter standby. This can be useful in 
    // machines that contain hardware that may be periodically turned 
    // off to save energy.
    //
    // If the printer has received this request and is then told to 
    // print, it will automatically leave the standby state. Otherwise,  
    // the PR_POWER_ON request may be used to cause the printer to 
    // reenable what was turned off.
    PR_POWER_STANDBY,

    // Instruct the printer to reset itself. This activity cycles the 
    // printer from the ON and idle state, to the OFF state, and back 
    // to the ON and idle state.
    PR_POWER_RESET
} PR_POWER_REQUEST;

typedef enum
{
    // The printer is powering off.
    PR_POWER_STATE_GOING_OFF,

    // The printer is powered off and will not accept any activity.
    PR_POWER_STATE_OFF,

    // The printer is powering on and is not ready for activity.
    PR_POWER_STATE_GOING_ON,

    // The printer is powered on and ready for any activity.
    PR_POWER_STATE_ON,

    // The printer is entering standby.
    PR_POWER_STATE_GOING_STANDBY,

    // The printer is in standby and not ready for any activity.
    PR_POWER_STATE_STANDBY,

    // This power state indicates the printer is powered on but in an 
    // error state such that requests to perform jobs or maintenance 
    // activities will fail. This power state is cleared when the error 
    // is resolved and the power state will change to 
    // PR_POWER_STATE_ON or PR_POWER_STATE_GOING_ON. See 
    // pr_error_recover() for details about recovering from printer 
    // errors.
    PR_POWER_STATE_ON_ERROR,

    // This power state indicates the printer is powered off but in an 
    // error state. This power state is cleared when the error 
    // is resolved and the power state will change to 
    // PR_POWER_STATE_OFF or PR_POWER_STATE_GOING_OFF. See 
    // pr_error_recover() for details about recovering from printer 
    // errors.
    PR_POWER_STATE_OFF_ERROR,

    // Insert power states above this entry
    PR_POWER_STATE_LAST

} PR_POWER_STATE;

# define PR_POWER_STATE_STRING "GOING_OFF", \
                               "OFF", \
                               "GOING_ON", \
                               "ON", \
                               "GOING_STANDBY", \
                               "STANDBY", \
                               "ON_ERROR", \
                               "OFF_ERROR"

typedef enum 
{
    // One sided duplex or simplex. This is the default.
    PR_DUPLEX_OneSided,

    // Two sided duplex long edge.
    PR_DUPLEX_TwoSidedLongEdge,
    
    // Two sided duplex short edge.
    PR_DUPLEX_TwoSidedShortEdge,

    // Manual duplex. The printer will pause at the appropriate time 
    // and signal the UI that the output pages must be flipped.
    PR_DUPLEX_Manual
} PR_DUPLEX;

typedef enum 
{
    /** No collation */
    PR_COLLATE_NONE,

    /** Perform a reverse collate copy */
    PR_COLLATE_REVERSE,

    /** Perform a forward collate copy */
    PR_COLLATE_FORWARD,

} PR_COLLATE;

typedef enum 
{
    /** No formatting will be performed on the input image. */
    PR_LAYOUT_None=0,

    /** Fit 2 rotated and reduced pages per output sheet */    
    PR_LAYOUT_2UpLayout,

    /** Fit 4 rotated and reduced pages per output sheet */    
    PR_LAYOUT_4UpLayout,

} PR_LAYOUT;

typedef enum
{
    /* media not present in tray */
    PR_MEDIA_PRESENCE_NOT_PRESENT,

    /* media present in tray */
    PR_MEDIA_PRESENCE_PRESENT,

    /* media presence unknown at this point */
    PR_MEDIA_PRESENCE_UNKNOWN,
} PR_MEDIA_PRESENCE;

typedef enum
{
    /* information determined using a sensor */
    /* and could not have changed since last sensing */
    PR_INFO_SOURCE_SENSOR_CURRENT,

    /* information determined using a sensor, */
    /* but could have changed since last sensing */    
    PR_INFO_SOURCE_SENSOR_HISTORICAL,

    /* set earlier by client through dc_pr_util_media_info_set() */        
    PR_INFO_SOURCE_CLIENT_INPUT,

    /* unchanged default value */
    PR_INFO_SOURCE_DEFAULT, 

    /* information source unkown, not typically used */
    PR_INFO_SOURCE_UNKNOWN,    
} PR_INFO_SOURCE;

typedef enum
{
    PR_STATUS_POWER=1000,
    PR_STATUS_POWER_STATE=1001,
    PR_STATUS_UTIL_BEGIN=1002,
    PR_STATUS_UTIL_CANCEL=1003,
    PR_STATUS_JOB_BEGIN=1004,
    PR_STATUS_DATA_COMPLETE=1005,
    PR_STATUS_PAGE_EJECTED=1006,
    PR_STATUS_JOB_CANCEL=1007,
    PR_STATUS_JOB_END=1008,
    PR_STATUS_ERROR_RECOVERY=1009,
    PR_STATUS_JOB_MEDIA_INFO_READY=1010,
    PR_STATUS_MEDIA_INFO_UPDATE=1011,    
    PR_STATUS_MEMORY_OUT=3000,
    PR_STATUS_INIT_MEMORY_OUT=3001,
    PR_STATUS_READY_FOR_PAGE = 3002,
    PR_STATUS_READY_FOR_JOB = 3003,
    PR_STATUS_PAGE_LOST = 3004,
    PR_STATUS_READY_FOR_DATA = 3005,
    PR_STATUS_LAST = 0,
} PR_STATUS_EVENT_COMMON;

typedef UINT32 PR_MEDIA_INFO_GET_FILTER;
typedef UINT32 PR_TRAY_INPUT;
typedef UINT32 PR_TRAY_OUTPUT;
//typedef UINT32 PR_STATUS_EVENT;
typedef UINT32 PR_JOB_ID;
typedef UINT32 PR_PAGE_ID;

#define	PM_SILENT	0
#if	PM_SILENT
#define PM_LOG(...) {}
#define PM_LOG1(...) {}
#else
#define PM_LOG(...) {dc_log_printf3  ("%s[%d]\t",__FILE__,__LINE__); dc_log_printf2(__VA_ARGS__);}
#define PM_LOG1(...) {dc_log_printf3  ("%s[%d]\t",__FILE__,__LINE__); dc_log_printf2(__VA_ARGS__);}
#endif

/******************************************************************************
*  3. DEFINES
******************************************************************************/
// Maximum length of status name
# define PR_STATUS_MAX_NAME 32

// Invalid Job identifier
# define PR_JOB_ID_INVALID 0xFFFFFFFF

// Printer will choose the tray that is best suited for the job:
# define PR_TRAY_AUTO 0xFFFFFFFE

// values for query_filter in dc_pr_job_tray_media_info_get()
#define DC_PR_JOB_TRAY_MEDIA_INFO_GET_PRESENCE  (1<<0)
#define DC_PR_JOB_TRAY_MEDIA_INFO_GET_TYPE      (1<<1)
#define DC_PR_JOB_TRAY_MEDIA_INFO_GET_SIZE      (1<<2)
#define DC_PR_JOB_TRAY_MEDIA_INFO_GET_ALL       0xFFFFFFFF

/******************************************************************************
*  3. STRUCTURE
******************************************************************************/

typedef void (*PR_STATUS_HANDLER)(PR_STATUS_TYPE event_type,
                             PR_STATUS_EVENT event_code,
                                  UINT32 clientRef,
                             void *arg1,
                             void *arg2,
                             void *arg3);

typedef struct PR_STATUS_REGISTER_STRUCT{
    PR_STATUS_HANDLER pFunc;
  UINT32 clientRef;
    struct PR_STATUS_REGISTER_STRUCT *pNext;
}PR_STATUS_REGISTER;


typedef struct{
    /**
    ** For machines with a hardware duplexer installed, this member is 
    ** for print duplex options.
    */
    PR_DUPLEX duplex;

    /**
    ** This member is for collate options.
    */
    PR_COLLATE collate;

    /**
    ** This parameter defines the layout of each printed page in the 
    ** job. 
    */
    PR_LAYOUT layout;

    /** 
    ** For print systems that contain more than one paper output tray, 
    ** this member is used to indicate which output tray is used for 
    ** the job.
    **
    ** This member is not valid for systems that do not contain a 
    ** multiple paper output trays.
    */    
    PR_TRAY_OUTPUT output_tray;

    /**
    ** This parameter defines the number of copies to print for the 
    ** job. If the RGB input image is used and the printer
    ** runs out of memory, the PR_STATUS_MEMORY_OUT event is 
    ** signaled. The system could respond by resending this page again 
    ** (e.g. multi-page copy with a flatbed scanner) or indicating an
    ** error to the user (e.g. mult-page copy with an ADF scanner).
    */
    UINT32 quantity;

    /**
    ** pointer to special custom job parameters
    ** 
    */
    void *custom;

} PR_JOB_PARAMETERS;

typedef struct
{
    /**
    ** Left margin values are used to adjust the position of the 
    ** composite output image on the output sheet with respect to the 
    ** printable area. This value is in 1000ths of an inch. 
    */
    INT32 horizontal_offset;

    /**
    ** Top margin values are used to adjust the position of the 
    ** composite output image on the output sheet with respect to the 
    ** printable area. This value is in 1000ths of an inch. 
    */
    INT32 vertical_offset;

    /**
    ** This parameter defines the width of the printed area in 1000ths   
    ** of an inch.
    */
    UINT32 width;

    /** 
    ** This parameter defines the height of the printed area in 1000ths 
    ** of an inch.
    */
    UINT32 height;

    /**
    ** This parameter defines a quality setting whose value is specific 
    ** to the printer.
    */
    PR_QUALITY quality;

    /**
    ** Margin mode for the page to allow the printer to determine
    ** the printable area of the input image when considering the 
    ** media size.
    */
    PR_MARGIN_MODE margin_mode;

    /** 
    ** For print systems that contain more than one paper input tray, 
    ** this member is used to indicate which input tray is used for the 
    ** job. 
    **
    ** This member is not valid for systems that do not contain a 
    ** multiple paper input trays.
    */
    PR_TRAY_INPUT input_tray;

    /** 
    ** This parameter is the expected output media size. The printer
    ** may signal a media mismatch error if this value does not match
    ** the media installed in the input tray selected for the job if
    ** the media_size_check parameter is TRUE. 
    */
    PR_MEDIA_SIZE media_size;

    /** 
    ** This parameter determines if the printer should perform media 
    ** size matching. The media_size is used for the comparison.
    */
    boolean media_size_check;

    /** 
    ** When media_size is PR_MEDIA_CUSTOM, this parameter defines
    ** the media size dimensions.
    */
    PR_MEDIA_DIMENSIONS custom_media_size;

    /** 
    ** This parameter is the expected output media type. The printer
    ** may signal a media mismatch error if this value does not match
    ** the media installed in the input tray selected for the job if
    ** the media_type_check parameter is TRUE. 
    */
    PR_MEDIA_TYPE media_type;

    /** 
    ** This parameter determines if the printer should perform media 
    ** type matching. The media_type is used for the comparison.
    */
    boolean media_type_check;

    /**
    ** This parameter is a pointer to the data container containing 
    ** image data. The storage for the buffer is the responsibility
    ** of the provider. The printer will not allocate storage for
    ** image buffer. It is possible for the printer to fail in error
    ** if the buffer is too small.
    **
    ** Note: Even if the image data is not completely available when
    ** the page is queued, it is required for the data container to be
    ** initialized. It should include color or black/white image
    */
    DC_IMGBUF *pImage;

    /**
    ** This parameter is a pointer to a string which names a color
    ** table resource to be used to convert the incoming RGB data from
    ** a device dependent color space into the sRGB color space used by
    ** the print subsystem. The print subsystem will apply this color
    ** conversion during its print processing. In most cases, this is
    ** is achieved by combining this color table with the native print
    ** engine color table. When delivering data in the standard sRGB 
    ** color space, this parameter should be set to NULL. This 
    ** parameter is only used when RGB source image data is specified.
    ** It is ignored when I (intensity) source image data is used.
    */
    char *pColorTable;

    /**
    ** This parameter is a pointer to the data container containing 
    ** per pixel content type data. The storage for the buffer is the 
    ** responsibility of the provider. The printer will not allocate 
    ** storage for the image buffer. It is possible for the printer to 
    ** fail in error if the buffer is too small.
    **
    ** Note: Even if the content type data is not completely available 
    ** when the page is queued, it is required for the data container
    ** to be initialized.
    */
    DC_IMGBUF *pContentType;

    /** 
    ** This parameter is a pointer to the optional image extent map to 
    ** help improve the processing of image data. If extent data is 
    ** not available, specify NULL.
    **
    ** Note: Even if the extent data is not completely available when
    ** the page is queued, the data container must be initialized.
    */
    DC_CIRCBUF *pExtentMap;

    /**
    ** Following two parameters (rotated, hflipped) specify orientation
    ** of the page as it's being transmitted to the printer. Based on
    ** values of these and other job wide parameters (e.g. N-up, duplex)
    ** printer will make appropriate operations to achieve desired output.
    ** 
    ** rotated | hflipped | Page orientation
    ** -----------------------------------------------------
    ** FALSE   | FALSE    | 0 dgr rotation (normal and default case)
    ** TRUE    | FALSE    | 180dgr rotation 
    ** FALSE   | TRUE     | Horizontally flipped (mirrored around horizontal axis)
    ** TRUE    | TRUE     | Vertically flipped (mirrored around vertical axis)  
    **
    */
    boolean rotated;
    boolean hflipped;
	
    /**
    ** pointer to a custom printer page parameters
    ** printer 
    */
    void *custom;

} PR_PAGE_PARAMETERS;

typedef struct 
{
    /**
    ** Printable area horizontal offset in 1000ths of an inch. This 
    ** value is the absolute offset from the physical top left corner 
    ** of the paper.
    */
    INT32 horizontal_offset;

    /** 
    ** Printable area vertical offset in 1000ths of an inch. This 
    ** value is the absolute offset from the physical top left corner 
    ** of the paper. 
    */
    INT32 vertical_offset;

    /** Width of printable area in 1000ths of an inch. */
    UINT32 width;

    /** Height of printable area in 1000ths of an inch. */
    UINT32 height;

    /** 
    ** This parameter assists in guiding the image source on how much
    ** data the printer productively uses to produce a quality 
    ** output.
    **
    ** This is the recommended width of image in pixels to prevent   
    ** image quality degradation. 
    */
    UINT32 source_width_pixels;

    /** 
    ** This parameter assists in guiding the image source on how much
    ** data the printer productively uses to produce a quality 
    ** output.
    **
    ** This is the recommended height of image in pixels to prevent   
    ** image quality degradation. 
    */
    UINT32 source_height_pixels;

    /** 
    ** This parameter assists in guiding the image source on how much
    ** data the printer productively uses to produce a quality 
    ** output.
    **
    ** In some cases, the print engine "tells a white lie" in reporting 
    ** the printable region.  For instance, when a job calls for 2-up
    ** layout on letter paper, the print engine may report a printable
    ** area close to or identical to that of 1-up letter paper, and 
    ** then apply a scale factor "behind the scenes".  This insulates
    ** most print clients from the details of 2-up printing.  The 
    ** scale_factor element can be used to determine when this "white
    ** lie" is being told.  When no behind the scenes scaling will be
    ** used scale_factor will report 100 (ie. 100%).  In the 2-up
    ** example, scale_factor may report a value of around 77.
    */
    UINT32 scale_factor;

} PR_PRINTABLE_AREA;

typedef struct PR_TRAY_MEDIA_INFO_t
{
    PR_TRAY_INPUT                   tray;    
    PR_MEDIA_PRESENCE               media_presence;
    PR_INFO_SOURCE                  media_presence_info_source;
    PR_MEDIA_SIZE                   media_size;
    PR_INFO_SOURCE                  media_size_info_source;    
    PR_MEDIA_TYPE                   media_type;
    PR_INFO_SOURCE                  media_type_info_source;

    /* pointer to next tray. If no more trays, set to NULL */
    struct PR_TRAY_MEDIA_INFO_t*    pNext_tray;
} PR_TRAY_MEDIA_INFO;

typedef struct PR_EXTENT_ENTRY_STRUCT {
   UINT32 leftMostNonWhitePixel;
   UINT32 rightMostNonWhitePixel;
   UINT32 preFilledWhiteByClient;
   UINT32 scanlineSkipped;
} PR_EXTENT_ENTRY;

/******************************************************************************
*  5. GLOBALS
******************************************************************************/
/******************************************************************************
*  6. PUBLIC FUNCTION PROTOTYPES
******************************************************************************/

/* setup and initialisation: */
DC_RETURN_CODE dc_pr_setup(
            void *pSetupParams,
            DC_MEM_PARAMS_t *pMemParams);

DC_RETURN_CODE dc_pr_init(
            DC_MEM_PARAMS_t *pMemParams);




/* Even and status interface: */
DC_RETURN_CODE dc_pr_status_register(
            PR_STATUS_REGISTER *pRegister,
            char *pName,
            PR_STATUS_HANDLER pFunc,
            UINT32 clientRef);

DC_RETURN_CODE dc_pr_status_unregister(
            PR_STATUS_REGISTER *pRegister);

// DC_RETURN_CODE dc_pr_status_get(PR_STATUS *pStatus);

/* Power State Management: */
DC_RETURN_CODE dc_pr_power(
            PR_POWER_REQUEST request);




/* Error recovery: */
DC_RETURN_CODE dc_pr_error_recover(void);




/* Printer utilities: */
DC_RETURN_CODE dc_pr_util_begin(
            PR_UTILITY_TYPE type,
            void *pParams);

DC_RETURN_CODE dc_pr_util_cancel(
            PR_UTILITY_TYPE type);

DC_RETURN_CODE dc_pr_util_media_info_get(
            PR_TRAY_MEDIA_INFO **ppAll_tray_media_info);

DC_RETURN_CODE dc_pr_util_media_info_set(
            PR_MEDIA_INFO_GET_FILTER config_filter,
            PR_TRAY_MEDIA_INFO media_info);


/* Job interface: */
DC_RETURN_CODE dc_pr_job_default_params_get(
            PR_JOB_PARAMETERS *pJob_params, 
            PR_PAGE_PARAMETERS *pPage_params);

DC_RETURN_CODE dc_pr_job_printable_area_get(
            PR_PAGE_PARAMETERS *pPage, 
            PR_JOB_PARAMETERS *pJob, 
            PR_PRINTABLE_AREA *pArea);

DC_RETURN_CODE dc_pr_job_begin(
            PR_JOB_ID *pJob_id);

DC_RETURN_CODE dc_pr_job_parameters_set(
            PR_JOB_ID job_id, 
            PR_JOB_PARAMETERS *pJob_params);


DC_RETURN_CODE dc_pr_job_tray_media_info_get(
            PR_JOB_ID job_id, 
            PR_TRAY_INPUT input_tray,
            PR_MEDIA_INFO_GET_FILTER query_filter,
            PR_TRAY_MEDIA_INFO *pMedia_info);

DC_RETURN_CODE dc_pr_job_page_begin(
            PR_JOB_ID job_id, 
            PR_PAGE_PARAMETERS *pPage_params, 
            PR_PAGE_ID *pPage_id);

DC_RETURN_CODE dc_pr_job_page_end(
            PR_JOB_ID job_id, 
            PR_PAGE_ID page_id);

DC_RETURN_CODE dc_pr_job_page_cancel(
            PR_JOB_ID job_id, 
            PR_PAGE_ID page_id);

DC_RETURN_CODE dc_pr_job_cancel(
            PR_JOB_ID job_id);

DC_RETURN_CODE dc_pr_job_end(
            PR_JOB_ID job_id);




/* Media utilities: */
PR_MEDIA_DIMENSIONS *dc_pr_media_default_get(void);

DC_RETURN_CODE dc_pr_media_name_search(
            char *name, 
            PR_MEDIA_SIZE *pMedia_size);

#ifdef __cplusplus
}
#endif

#endif// __DC_PRINTER_CONTROL_API_H__
